ciftiTools Demo for SMI 2022

Damon Pham & Amanda Mejia

5/25/2022

NIFTIs, GIFTIs, & CIFTIs

  • NIFTI: voxel-based
    • [...].nii.gz

  • GIFTI: surface-based
    • [...].surf.gii
    • [...].func.gii
    • [...].label.gii

  • CIFTI: gray matter
    • [...].dtseries.nii
    • [...].dscalar.nii
    • [...].dlabel.nii

From NIFTI to CIFTI

From NIFTI to CIFTI

Anatomy of a CIFTI file

Anatomy of a CIFTI file

What’s missing?

B.Y.O. surfaces

Why use CIFTI files?

Advantages of surface-based analyses for cortical gray matter (Fischl et al., 1999; Anticevic et al., 2008; Van Essen, 2012; Glasser et al., 2016; Coalson et al., 2018; Brodoehl et al., 2020)

  • More appropriate smoothing
  • More accurate spatial modeling
  • Better inter-subject alignment
  • Reduced dimensionality

Doesn’t omit the subcortex

What is ciftiTools?

  • Convenience
  • Reproducibility
  • Extensibility

What is ciftiTools?

What is ciftiTools?

What is ciftiTools?

What is ciftiTools?

Example: Compute summary stats

xii <- read_xifti(
  "data/MyelinAndCorrThickness.dscalar.nii",
  brainstructures="right", resamp_res=2000
)
xii <- scale_xifti(xii)
round(apply_xifti(xii, 2, summary), digits=2)
##         MyelinMap_BC_decurv corrThickness
## Min.                  -2.04         -3.64
## 1st Qu.               -0.72         -0.50
## Median                -0.17          0.09
## Mean                   0.00          0.00
## 3rd Qu.                0.62          0.62
## Max.                   4.72          3.98

Example: Interactive visualization

view_xifti_surface(
  xii, idx=seq(2), view="lateral", widget=TRUE,
  zlim=c(-4, 4), colors="RdYlBu"
)

Let’s get started!

Let’s move to demo.rmd and complete the preliminary task:

Install and set up ciftiTools.

https://tinyurl.com/ciftiTools-SMI https://github.com/damondpham

Task 1: Practicing the basics

The first task introduces a few core ciftiTools functions.

\(~\)

Read in a resting-state fMRI session. Plot the first timepoint.

\(~\)

Compute the fALFF* for this session. Plot it.

\(~\)

*fractional amplitude of low-frequency fluctuations

Working with the data matrix

For more complex data manipulation:

  1. Extract the data matrix with as.matrix
  2. Manipulate as desired
  3. Plug the result back into the "xifti" object with newdata_xifti

Example: Compute PCA

xii <- read_cifti("data/MSC.4k.dtseries.nii")
z <- as.matrix(xii) # 1.
z <- scale(z, scale=FALSE) # 2.
z <- svd(z / (nrow(z)-1))$u
xii <- newdata_xifti(xii, z) # 3.
plot(xii, zlim=c(-.04, .04))

Working around the medial wall

Working around the medial wall

Working around the medial wall

Working with the data matrix, v2

For more complex data manipulation, including the medial wall:

  1. Fill the medial wall with NA using move_from_mwall
  2. Extract the data matrix with as.matrix
  3. Manipulate as desired
  4. Plug the result back into the "xifti" object with newdata_xifti
  5. Move NA values back using move_to_mwall

Task 2: Seed-based correlation

Your turn! Let’s try the next task:

\(~\)

Compute the seed-based correlation for a selected parcel.

\(~\)

Write out the result. Plot it too!

Task 3: Building from ciftiTools

In this last task we will practice writing a function that builds on top of ciftiTools.

\(~\)

To get an idea of how that works, we’ll explore BayesfMRI, a package that uses ciftiTools.

BayesGLM source code excerpts

BayesGLM_cifti

# [...]
  for (ss in 1:n_sess) {
    # [...]
  
    if (is_xifti) {
      xii_ss <- cifti_fname[[ss]]
    } else {
      xii_ss <- read_cifti(
        cifti_fname[ss], brainstructures=brainstructures,
        resamp_res=resamp_res
      )
    }
    
    # [...]
    mwallL_ss <- xii_ss$meta$cortex$medial_wall_mask$left
    mwallR_ss <- xii_ss$meta$cortex$medial_wall_mask$right
    ntime[ss] <- ncol(xii_ss)
    
# [...]
  if(do_Bayesian){
    if(do_left) datL <- BayesGLM_results$left$beta_estimates[[ss]][mwallL==1,]
    if(do_right) datR <- BayesGLM_results$right$beta_estimates[[ss]][mwallR==1,]
    BayesGLM_cifti[[ss]] <- as.xifti(
      cortexL = datL,
      cortexL_mwall = mwallL,
      cortexR = datR,
      cortexR_mwall = mwallR
    )
    BayesGLM_cifti[[ss]]$meta$cifti$names <- beta_names
# [...]

BayesGLM source code excerpts

plot.BayesGLM_cifti

# [...]
  ciftiTools::view_xifti_surface(x[[method]][[session]], idx=idx, zlim=zlim, ...)
# [...]

Task 3: building from ciftiTools

Complete combine_and_plot_GLM, and try it out!

Thanks! Questions?